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Feedback 


Please send all feedback to assembly@qdosmsq.dunbar-it.co.uk. You may also send articles 
to this address, however, please note that anything sent to this email address may be used in a future 
issue of the eMagazine. Please mark your email clearly if you do not wish this to happen. 


This eMagazine is created in 4I¢Xsource format, aka plain text with a few formatting commands 
thrown in for good measure, so I can cope with almost any format you might want to send me. As 
long as I can get plain text out of it, I can convert it to a suitable source format with reasonable ease. 


I use a Linux system to generate this eMagazine so I can read most, if not all, Word or MS Office 
documents, Quill, Plain text, email etc formats. Text87 might be a problem though! 


Subscribing to The Mailing List 


This eMagazine is available by subscribing to the mailing list. You do this by sending your 
favourite browser to http: //qdosmsq.dunbar-it.co.uk/mailinglist and clicking on the 
link “Subscribe to our Newsletters”. 


On the next screen, you are invited to enter your email address twice, and your name. If you wish 
to receive emails from the mailing list in HTML format then tick the box that offers you that option. 
Click the Subscribe button. 


An email will be sent to you with a link that you must click on to confirm your subscription. Once 
done, that is all you need to do. The rest is up to me! 


1.3 


2 Chapter 1. Preface 


Contacting The Mailing List 


I’m rather hoping that this mailing list will not be a one-way affair, like QL Today appeared to be. 
I’m very open to suggestions, opinions, articles etc from my readers, otherwise how do I know 
what I’m doing is right or wrong? 


I suspect George will continue to keep me correct on matters where I get stuff completely wrong, as 
before, and I know George did ask if the list would be contactable, so I’ve set up an email address 
for the list, so that you can make comments etc as you wish. The email address is: 


assembly@qdosmsq.dunbar-it.co.uk 


Any emails sent there will eventually find me. Please note, anything sent to that email address will 
be considered for publication, so I would appreciate your name at the very least if you intend to 
send something. If you do not wish your email to be considered for publication, please mark it 
clearly as such, thanks. I look forward to hearing from you all, from time to time. 


If you do have an article to contribute, I'll happily accept it in almost any format - email, text, Word, 
Libre/Open Office odt, Quill, PC Quill, etc etc. Ideally, a IATRXsource document is the best format, 
because I can simply include those directly, but I doubt I'll be getting many of those! But not to 
worry, if you have something, I'll hopefully manage to include it. 


LJ 


oe 


Part of a little program that I’m working on requires the characters of a word to be sorted into order, 
ascending in this case, and as there’s no trap or vector in QDOSMSQ to allow this to be easily done, 
I’ve had to work out my own. The bubble sort is one of the simplest sorting algorithms that there is, 
however, it is pretty inefficient as much of the work it does is checking over data that it has already 
sorted in any previous pass. Also, the more data there are to sort, the longer it takes to sort. Much 
longer in fact. 


Looking on Wikipedia for some slightly improved versions, I found the one below. It doesn’t 
reduce the number of swaps that take place, but it does ‘know’ that when it has made a pass through 
the array of bytes, in this case, the last item that it swapped is the lowest possible value for this 
pass, and anything from that point on in the array is already sorted. By ‘knowing’ it does at least 
reduce the number of comparisons that have to be made on each pass, which reduces the run time 
of the sort. 


The data is sorted by moving the higher values - in this version - down the array, one place at a 
time, until the array’s bottom end contains all the sorted data, while the top end contains the data 
that are yet to be sorted. Hopefully, the following will make things a bit clearer, the pseudo code 
was obtained from Wikipedia. 


Blatantly stolen from Wikipedia! 
Very slightly modified by Norman Dunbar. 


An improved BubbleSort which ‘knows’ that after each pass, the lowest 
item(s) must be already sorted. 

For example: 

9 1 3 4, after pass 0, becomes: 

i 3) 4 9 so we stop at ‘4’ next time, not at ‘9’. 


SOANADANMNFWN Ke 


—y 


Ly 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 


14 Chapter 2. Bubble Sorts 


bubbleSort( A: list of sortable items ) 
n = length(A) 
repeat 


end procedure 


> 


Listing 2.1: Bubblesort Algorithm 


From the above algorithm, we can see that a byte of data will be looked at and using comparisons 
and swaps, will ‘bubble’ its way to the lower end of the array - that’s the bit furthest from the word 
count ina QDOSMSQ string, for example. 


An example is called for, we start with the test harness which sets up a tiny array of 4 upper case 
letters, with a leading word count, and sorts it. 


start 
lea stuff ,al ; Where the data are 
bsr.s print_it ; Print data to #1 unsorted 
bsr.s bubblesort 2 IDOL wrulil Ine Zeire 
bsr.s print_it ; Print sorted data to #1 
rts 


stuff dc.w stuff_end—stuff —2 
dc.b SG AS Da: Be 
stuff_end equ * 


Listing 2.2: Bubblesort Test Harness 


The code above needs to call a helper routine to print the before and after data, that code follows 
and is a slightly modified version of the code to find channel #1 and print a string, from the last 
issue where we were printing the name list. 


; Some hopefully familiar code from last issue, to print some data 
; to channel #1 which MUST BE OPEN. 


bv_chbas equ $30 ; Offset to channel table. 


; Find #1 in the channel table. We shouldnt be off the end of the 
; table , so NOT CHECKED. 
; We assume #1 is open too, so that’s NOT CHECKED for either. 
print_it 

move.1 al,—(a7) 2 ANI TS Ul WHE, PKESerYe i 


findChan 
moveq #40,d1 5 Oinrser We Cimlinny el 
move.1 bv_chbas(a6),a0 ; Channel table base offset 
adda.1 dl,a0 ; Required entry for #1 
move.1 0(a6,a0.1),a0 ; AO is ID of channel #1 


S Print thee text wWemkead sihrOmsthcuname list COMmnG hammell si ln 
5 (corms IDISDS/UNIl, JPreseryes AOYMSNs),, 100) = Girir@ir eoGls, 
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printText 
move.w ut_mtext ,a2 ; Vector to print a string 
jsr (a2) 5 Piet at 


Jee nint sae lainicke cde tomchammie lard le 
; Corrupts DIl/Al. Preserves D2—D3/A0/A2—A3. DO = error code. 


linefeed 


moveq #io_sbyte ,d0 Printed Dyes munalp 
moveq #10,d1 ee uneteederchianacter 
moveq #—1,d3 ; Timeout 

trap #3 Domi 

move. 1 (a7)+,al ; Retrieve Al 

rts 


Listing 2.3: Bubblesort Test Harness 


So far so simple, the following is my version of the pseudo code from Wikipedia, converted into 
assembly language. The labels are named in such a way as, hopefully, to give you an idea of where 
we are in the pseudo code as converted. Some bits don’t convert exactly, the FOR loop, for example, 
starts with D2=0 and gets incremented by 1 before the loop, not at the end as per a normal FOR 
loop. But you get the idea, I hope! 


The working registers are listed in the comments so that you can, if you wish, follow what’s going 
on. 


; ENTRY: 


Ale — Start saddnesseson | byites milton bes onved es Wordcount sn insit. 


; WORKING: 


2 ANI IL S Slew AGWGRESS Ol DWiIGS tO We SOrieG. wore COMM! JOUTST - 
; A2.L = Bytes being compared right now. (—1(a2) and (a2)). 

2 DOW = n= end of unsorted) data. 

; D1.B = Temp for swapping. 


6 D2 MWS “1°? = loop CoOUmMier . 

2 IDSA = “meyin™ = Ils men S@irieal . 
2 japgire 

- DORE = 0k 


2) 


; Al.L = Preserved — Start address of sorted bytes word count. 


2.0.1 
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wll Mothen snice tsten Sm preserved: 
bubblesort 
movem.!1 dl—d3/al—a2,—(a7) 
move.w (al )+,d0 2 IN = Jermyn (Ca) 
beq.s bs_done 
subq.w #1,d0 ; We need n—1 when testing 
bs_repeat equ * ; Repeat 
movea.1 al ,a2 : A2 = First unsorted byte 
moveq #0,d3 : Newn = 0 
bs_for_loop 
moveq #0,d2 : For 1 = 1 ter n—1 
bs_next 
addq.b #1,d2 
move.b (a2)+,dl : Temp = A[i-1] 
cmp.b (a2),dl : If Temp > A[i] then 
bls.s bs_end_if Skip swap if A[i-—1] <= A[i] 
bs_swap 
move.b (a2),—1(a2) is A[i-1] = A[i] 
move.b dl ,( a2) 3 Al) Se" temp 
move.w d2,d3 : Newn = i 
bs_end_if equ * : end if 
cmp.w d2,d0 : I = n—l1 yet? 
bne.s bs_next : End for 
move.w d3,d0 z N = newn 
tst.w dO ; N= © wer? 
bs_until 
bne.s bs_repeat 5 Win) im = (0) 
bs_done 
movem.1 (a7)+,d1—d3/al—a2 
clr.1 dO 
rts 


Listing 2.4: Bubblesort 


So, type the above into a file, save it, assemble it in the usual manner with Gwasl and then load it 
into a reserved area of memory (mine is 98 bytes long) and simply CALL it. You should see two 
lines of text on channel #1. The second line being the sorted version of the first. 


Useful Improvements 


The above is fine for sorting the characters in a QDOSMSQ string, and that’s the only sorting I 
actually need for my current little project, however, with a couple of minor changes, we can make it 
even more useful and allow us to sort words, longs and even arrays of strings, if we wish. One way 
to do this would be to duplicate the code above as many times as we need and edit it accordingly, 
but that is wasteful even in these days of QPC and other emulators allowing multi-megabytes of 
RAM. We need a little redesign. 


7 


If we extract the compare and swap code to a separate subroutine, we can call it from the main loop, 
but rather than using a BSR instruction, we can use an address register to hold the compare and swap 
code’s address, and use JSR (An) instead. That way, we only need to set up the address register 
once, with the desired compare and swap code’s address, and we can reuse most of the above code. 


Here’s the slightly more useful version of the above code - which can replace the above, from line 


51 onwards. 


5 JBINIIRNG 


; For entry at label bubblesort: 


JAN Eee Sitar taididielsis 


to be sorted. Word count first. 


; WORKING: 


5 NII = Siac AvalGhrese 


to) be sorted), word count first. 


; A2.L = Data being compared right now. (—1(a2) and (a2)). 
; A3.L = Address of the Compare and swap routine. 
7 DOW. = sn S=send of sumsion ted @idiat ar 


; D1.B = Temp for swapping. 


sorted. 


5 DAMS 91 = loop Commer. 
2 IDS AW = “meal = IAS 

5 leone 

2 DORE = Or 


TAS seneseuvedu— stan 


address of sorted bytes 


> 


word count. 


3 All OUNGr RESISKOrS jpreSem7eGl 


bubblesort 


movem.|] dl—d3/al—a2,—(a7) 


move.w (al)+,d0 
beq.s bs_done 
subq.w #1,d0 


bs_repeat equ * 
movea.1 al,a2 
moveq #0,d3 


bs_for_loop 
moveq #0,d2 


bs_next 
addq.b #1,d2 
jsr (a3) 


bs_end_if equ * 
cmp.w d2,d0 
bne.s bs_next 
move.w d3,d0 
tst.w dO 


bs_until 
bne.s bs_repeat 


PN = —sallemrent huGay) 


; We need n—1 when testing 


; Repeat 

‘ A2 = First unsorted byte 
3 Newn = 0 

: For i= 1 to n-l 


; Compare and swap if necessary 


di end if 

: I = n—1 yet? 
: End for 

z N = newn 

z N= © yen? 


ee Winiitlene— 0) 


99 
100 
101 
102 
103 


104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
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bs_done 
movem.1 (a7)+,d1—d3/al—a2 
clr.1 dO 
rts 


Listing 2.5: Better Bubblesort 


In the three example compare and swap routines, see Listing 2.6, 2.7 and 2.8, the usage of the 
working registers is described in Table 2.1. 


Register Description 


A1.L Start Address of data to be sorted. 

A2.L Data being compared right now. 

A3.L Address of the Compare and swap routine. 
DO.W_ ‘n’ = end of unsorted data. 

D1.B Temp for swapping 

D2.W ‘i’ = loop counter 

D3.W _ _ ‘newn’ = last item sorted 


Table 2.1: Working Registers for Bubblesort Compare and Swap Code 


cas_b 

move.b (a2)+,dl ; Temp = A[i-1] 

cmp.b (a2),dl ; If Temp > A[i] then 

bls.s casb_exit z Skip swap if A[i-—1] <= A[i] 
casb_swap 


move.b (a2),—1(a2) ; A[i-1] = ATi] 

move.b dl ,( a2) 2 ANT ]) = AWesayy 

move.w d2,d3 a Newne— a 
casb_exit rts 


Listing 2.6: Bubblesort - Compare and Swap - Bytes 


The first action required by the code is to grab the current value to be compared. This is pointed to 
by A2 on entry and is incremented to point at the next entry. In the above, this is byte sized, but see 
Listing 2.6, 2.7 and 2.8 for subroutines that compare and swap word and long word sized data. The 
data from the table is loaded into the ‘temp’ variable, also known as D1.size, where size is .B, .W 
or .L appropriately depending on which compare and swap code we are running. 


The comparison between table entries A[i-1] and A[i], from the pseudo code description, actually 
compares ‘temp’ with ‘A[i]’, or D1.size with (A2), but it’s the same comparison. 


In the event that the data in D1 is larger (in this case) than the data in the table pointed to by A2, a 
swap is made and we set ‘newn’ to the index of the last swap made. We only swap when D1 is 
larger, that way we don’t end up swapping data that are the same. We are running an inefficient 
algorithm after all, there’s no need to make it any more inefficient than we have to. 


The ‘newn’ variable tells the main loop of the code to stop comparing because whatever index into 
the table was last swapped, is where the sorted part of the table begins. We don’t need to compare 
our current value (in D1) with any entries in the table from ‘newn’ onwards. 


The following two subroutines can be used to sort arrays of word and/or long words. All that was 
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changed was the size of the data loaded into D1, the CMP instruction and the data that are swapped 
around. 


cas_w 
move.w (a2)+,dl ; Temp = A[i-1] 
cmp.w (a2),dl li Temp) = All| then 
bls.s casw_exit s Skip swap if A[i-—1] <= A[i] 


casw_Swap 


move.w (a2),—2(a2) ; A[i-1] = ATi] 

move.w dl ,( a2) eA ees eemp 

move.w d2,d3 + Newn = 1 
casw_exit rts 


Listing 2.7: Bubblesort - Compare and Swap - Words 


cas_l 

move.1 (a2)+,dl ; Temp = A[i-1] 

cmp.1 (a2),dl ali Tempe eA) |eithien 

bls.s casl_exit : Skip swap if A[i—1] <= A[i] 
casl_swap 

move.! (a2),—4(a2) ; Afi-1] = ATi] 

move.1 dl ,( a2) 2 JN) SS Wesaiy) 

move.w d2,d3 ; Newn = i 
casl_exit rts 


Listing 2.8: Bubblesort - Compare and Swap - Long Words 


In our test harness, the code requires to be modified to add a pointer to the desired compare and 
swap routine in register A3, as follows: 


start 
lea stuff ,al ; Where the data are 
lea cas_b,a3 ; Compare and swap bytes 
bsr.s print_it ; Print data to #1 unsorted 
bsr.s bubblesort DO ie wallibesZe no 
bsr.s print_it Pe mintensonved eda baton 
rts 

stuff 
dce.w stuff_end—stuff —2 
dcab Ge. fA Die B: 

stuff_end equ * 


Listing 2.9: Bubblesort Test Harness Revisited 


If we were sorting an array of word or long word data, we would simply point A3 at the appropriate 
subroutine, and that’s the only difference. 


So far, so good, we have the ability to sort bytes, word and long word based data. What about 
strings? Well, they are a little different and comparing strings is slightly more complicated than a 
simple cmp.1 (a2) ,d1 instruction, for example. I'll continue with string sorting in the next issue, 
for now, we can be satisfied with bytes, words and long words. 


There, I think that’s all sorted now! 


——_ a 


3. Printi ) Strings at Once 
ET. a” 


Have you ever needed to print multiple strings, one after the other, perhaps with a linefeed between 
each one? Neither have I until recently. So if you ever find yourself needing to do exactly that, then 
the following short utility might be of some help. 


MULTIPRINT: Prints numerous strings to the channel in AO.L from a 
table of strings at Al.L. The table format is as follows: 


S Sieimes Chewy m ; How many strings? 
a as i1 dc.w sle—sl—2 . pigs OF Sines Il 
: derbi: > ; Bytes of string | 
5 Sile ds.w 0 ; Padding byte if required 
2 $2 dc.w s2e—s2—2 5 Size Ol Birine 2 
: dic Aber s LIWIES Oi Siig 2 
VAS ds.w 0 jeeaddime byte wit ene quaned 


: ; And so on. 


; REGISTER USAGE: 
5 JENN 


; AO.L = Channel ID to be used for output. 
2 SAIS Start of strings table. 


2 (EX 


5 IDOL S iirrer code Or Zer®, 4 las set accorrchline)isy . 
2 ANI JL = (Corrie! ; 
5 ZU] WUNE LEWISISrS jorresernyecl 


; ENTRY POINTS: 
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; MULTIPRINT — Enter here to print the table of strings exactly as is 
; with no additional linefeeds etc between strings. If you want any 
6 JNMNIGISEGS , WOU MECC 1G Genie WE Wm His SurimMss - 

; MULTIPRINT_LF — Enter here to print the strings with a linefeed 

5 [oeiMieGl Ee CEell Core. Were wil lye ey JhinesieeGl en Wie Ciel, eed 
5 tle jimall sSirimg tO. 

; WORKING REGISTERS: 

6 ID Ib = SON i IniGreecs Are reGgMesied , 2er© OUNEIMNVISE . 

S DAM = Suess Stil ie prin CoOmimiuere . 

7 AOR — Channels IDS bens printed tom 

Al Ee — Runnin ® poimier TO next st rinic, stom prints 

; A2.L = Used to call QDOSMSQ vector to print a string. 

; Others — As required by QDOSMSQ vectors and trap calls. 


timeout 
linefeed 


equ —l 
equ $0A 


> 


Timeout for TRAP #3 calls 


aimeheeducinamaetien 


cy 


; MULTIPRINT_LF . 


Multiprint_lf 
move.1 d7,—(a7) 
moveq #linefeed ,d7 
bra.s mp_saveregs 


Save Linefeed 
We want linefeeds 
And drop in below 


indicator 


2 


; MULTIPRINT. 
Multiprint 
move.1 d7,—(a7) 5 SCS TMA TER 
lie sll li a Nom linietcieds sriedquared 


mp_saveregs 


movem.!1 dl—d3/d6—d7/a2,—(a7) 


move.w (al )+,d6 
bra.s mp_next 


mp_loop 
move.1 al,—(a7) 
move.w ut_mtext ,a2 
jst (a2) 
bne.s mp_oops 
move.1 (a7)+,al 
adda.w (al),al 
addq.1 #3,al 
move.1 al,d5 
bclr #0,d5 
move.1 d5,al 


mp_lf 
move.b d7,dl 
beq.s mp_next 


> 


? 


; Save working registers + D7 again! 


Fetch counter avaliuie 
Skip loop first time 


Save current string 
Goruhicm viector 

Prinite ec UTnhemite sit G1 me 
Something bad happened 
Start of current 
Add size word 
Prepare to make even 
next 


D5 now points at 


Back into Al 


Einetcedior sZeno 
Not printing linefeeds 


string 


string 


3.0.2 


3.0.3 


BRWN Re 
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moveq #io_sbyte ,d0 e IPielimi: 2 layire 

moveq #timeout ,d3 

trap #3 2 Jerimi: Iimeteec! 

tst.1 dO 

bne.s mp_done ; Something bad happened 
mp_next 

dbf d6,mp_loop ; Go around again 

clr.1 dO a Nome nnonsesdetected 

bra.s mp_done ; Clean up on the way out 
mp_oops 

adda.l #4,a7 ; Remove saved Al.L 
mp_done 

movem.1 (a7)+,d1—d3/d6—d7/a2 ; Restore working registers 

move.! (a7)+,d7 ; Restore original D7 again 
mp_exit 

tst.1 dO ; Set the Z flag as necessary 

tts 

Listing 3.1: Multiprint Utility 

Stacking D7 Twice? Why? 


When I originally wrote this code, I explicitly saved the entry value of register D7, by itself, in 
multiprint_1f but not inmultiprint where it was the linefeed indicator value that was stacked 
along with the other working registers. When the code was almost done, it popped the working 
registers off the stack and checked D7 for zero at mp_done. If it was not zero, I popped D7 off the 
stack again - assuming that we had entered at multiprint_1f. Can you see the ever so slightly 
insidious bug there? 


What happens if I enter the code at multiprint with D7 already set to zero, when the utility was 
done, it would pop D7 off the stack, and check it and on finding it to be zero, would attempt to pop 
another D7 off the stack, assuming that we had entered at multiprint_1lf. D7 would be loaded 
with the calling code’s return address from the stack as opposed to its original value, and so the 
final RTS would cause a crash. 


The solution is as per the code above, D7 gets stacked by both utility routines and will always be 
popped off at the end, twice. That helps keep the stack neat and tidy and avoids this particular 
intermittent bug/crash. 


Testing MultiPrint 


To test the utility code, all you need is something line the following which I’ve saved typing time 
and effort by setting up as yet another filter program which allows me to pass a channel number on 
the command line, and the output will go to that channel. Lazy? me? ;-) 


me equ —1 ; This job 
channel_id equ $02 Te Ontiset (AM) to input miles td 
start 
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bra start_2 
dce.1 $00 
dc.w $4afb 
name 
dc.w name_end—name—2 
dc.b ’MultiPrint Test’ 
name_end equ * 
version 
dc.w vers_end—version —2 
dc.b ’Version 1.00’ 
vers_end equ * 
str_table 
dc.w 4 
sl dc.w sle—sl—2 
dc.b *This is a demo of MultiPrint ’ 
sle equ * 
ds.w 0 
$2 dc.w s2e—s2—2 
dc.b *which shows how easy it is to ’ 
s2e equ * 
ds.w 0 
s3 dc.w s3e—s3—2 
dc.b ’print multiple strings in one easy manner. ’ 
s3e equ * 
ds.w 0 
s4 dc.w s4e—s4—2 
dc.b ’ Written by Norman Dunbar’ , $0a 
s4e equ * 
ds.w 0 
start_2 


move.1] channel_id(a7),a0 
lea str_table ,al 
bsr MultiPrint 3 


lea str_table ,al z 
bsr MultiPrint_lf : 


moveq #0,d3 ; 
moveq #mt_frjob ,d0 
moveq #me,dl : 
trap #1 


in "raml_MultiPrint_lib” 


‘ec hrammie lid! 
Table of strings 
Print with no linefeeds 


Table of strings again 
Print with linefeeds between 


No error code 


This job is about to die 


Listing 3.2: Testing the Multiprint Utility 


BRWNFR 
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And finally, the ram1_MultiPrint_lib file will look like this. However, if you have changed the code 
layout above (for MultiPrint_asm) then you may have to regenerate the lib file using the SYM_bin 
utility. 


MULTIPRINT_LF EQU *+$00000000 
MULTIPRINT EQU *+$00000006 


lib "ram1l_multiprint_bin" 


Listing 3.3: The Multiprint Library File 


You should execute the test harness as follows: 
ex raml_MultiPrint_test_bin, #1 


Listing 3.4: Executing the Multiprint Test Harness 


And the output will be something like the following: 


This is a demo of MultiPrint which shows how easy it is to print 
multiple strings in one easy manner. Written by Norman Dunbar 
This is a demo of MultiPrint 

which shows how easy it is to 

print multiple strings in one easy manner. 

Written by Norman Dunbar 


Listing 3.5: Results of the Multiprint Test Harness 


The first couple of lines shows the data printed “as is” without linefeeds. The remainder of the 
output shows each string printed with a separating linefeed. 


Because I had my channel #1 defined as a quite narrow window, the first line of output wrapped 
around onto the next line, in the normal manner of printing long strings. 


Because there are now two linefeeds after the final string, we get a blank line after the final one. Or, 
we will when the next print to that channel takes place, it’s possible that QDOSMSQ has the final 
linefeed as pending. I noticed that in testing occasionally. 


> 
| 4. Hexd 


I’m a frequent user of the Linux/Unix hexdump utility in my real life, and I miss it on QDOSMSQ. 
I decided to put that right and as a continuation of the use of filter utilities in a previous issue, I 
decided to make this utility a filter too. 


To execute the utility, you simply: 
ex winl_hexdump_bin, source_file , dest_location 


Listing 4.1: Executing the Hexdump Utility 


The source file should be obvious, it’s the one you want to examine, and the dest_location can be 
either a filename or a channel number. 


So, without any further ado, here’s the code. [ll explain it at the end, but it’s fairly simple. 


Hexdump Listing 


; HEXDUMP: 


; A filter program using an input and output channel, passed on 
2 (ine Stack Tor wis miles . 


; EX hexdump_bin, binary_file , output_file 


; 21/09/2015 NDunbar Created for QDOSMSQ Assembly Mailing List 


; (c) Norman Dunbar, 2015. Permission granted for unlimited use 
; or abuse, without attribution being required. Just enjoy! 


me equ —l ; This job 
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infinite equ —l ; For timeouts 
err_bp equ —15 ; Bad parameter error 
linefeed equ $0A a Lineteed eehianacter 
eof equ —10 ; End of file 
buff_size equ $10 ; Maximum size of read buffer 
out_size equ 73 ; Output string length 
space equ”? ’ “lees pace 
dot equ ’.’ leeds 
max_char equ $CO ; Highest printable ASCII character 
source_id equ $02 ; Offset(A7) to input file id 
dest_id equ $06 7 Ottser (Avy) tol output stalemaid 
param_size equ $0A ; Offset(A7) to command string size 
param equ $0C ; Offset(A7) to command bytes 
start 
bra Hexdump 
dc.1 $00 
dc.w $4afb 
name 
dc.w name_end—name—2 
dc.b *Hexdump’ 
name_end equ * 
version 
dc.w vers_end—version —2 
dc.b ’Version 1.00’ 
vers_end equ * 
in_buffer 


ds.1 4 


out_buffer 
ds.1 20 


’ 


> 


open_bracket equ out_buffer+54 


close_bracket equ out_buffer+71 


16 bytes read at a time 


80 bytes max output 


Witenes. | shouldbe 
; Where °]|’ should be 


5 WUAGI< Gin CMUiry 3 


; $0c(a7) = bytes of parameter + padding, if odd length. (Ignored) 


; $0a(a7) = Parameter 


; $06(a7) = Output 


size word. 
file channel 
; $02(a7) = Source file channel 


(Ignored ) 
id. 
rife! 


; $00(a7) = How many channels? Should be $02. 


bad_parameter 


moveq #err_bp , dO ; 


bra suic 


Hexdump 


ide 


> 


cmpi.w #$02 ,(a7) ; 


Guess ! 
Die horribly 


Two channels is a must 


73 
74 
75 
16 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
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bne.s bad_parameter ; Oops 
start_loop 
moveq #infinite ,d3 ; Timeout — preserved throughout 


ellie ll ly S (Cire MOC ainGiml wy iille 


read_loop 


move.1 source_id(a7),a0 ; Input channel id 

lea in_buffer ,al Where tom readmit hic davai to 

moveq #buff_size ,d2 ; Maximum size of the buffer 

moveq #io_fstrg ,d0 ; Trap utility we want 

trap #3 2 JkeaGl 6 Cliiil< @t SoOueGE Wille 

tst.1 dO ; Did it work? 

beq.s read_ok a Not EOE V yet rcarnysson! 

cmpi.1 #eof ,d0 ; EOF? 

bne error_exit ; Something bad happened 

tst.w dl ; Any remaining data? 

beq all_done ; No, exit the main loop 
read_ok 

lea in_buffer ,a2 5 Source lywiiteir 

lea out_buffer ,al ; Output buffer 

moveq #79,d0 2 0) lDwWwies ie) ellen 


> 


; Space fill the entire output buffer on each pass through the 


loop. 


ob_clear 


move.b #space ,(al,d0.w) ; Space fill from the end back 
dbf d0,ob_clear ; And do the rest 
moveq #0,d5 © Jabeiin Ihimeieecl eomimtieir 


r 


7 Add the address) to the bivfitien as) 8 hex  chianacters. Then 4 spaces- 


hd_address 


move.1 d7,d4 ; D4 is required here 

beq.s hd_continue “No wextraluneheed at stant 
cmpi.b #0,d7 ; On a 256 Byte boundary? 
bne.s hd_continue ; Nope. 

move.b #linefeed ,(al)+ ; Yes, extra linefeed 

moveq #1,d5 ; Adjust counter 


hd_continue 


eecig ll lil ; Curently only word sized 
add.1 dl,d7 | Update ile offset. counter 
bsr hex_l ; Store address in buffer at Al 
adda.l #4,al ; Leave 4 spaces 


? 


; There might not always be 16 bytes to convert. Adjust the count to 


; add groups of 4 bytes then two spaces to the output buffer , 
; counting long words and then the remaining spare bytes. 


by 


hd_data 
move.1 dl,d0 7 Byte scounten lone “sized ) 


129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 
183 
184 
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divu #4,d0 
bra.s hdl_next 


hdl_loop 
move.1 (a2)+,d4 
bsr.s hex_l 
adda.1 #2,a1 


hdl_next 
dbf d0,hdl_loop 


swap dO 

bra.s hdb_next 
hdb_loop 

move.b (a2)+,d4 

bsr.s hex_b 
hdb_next 


dbf d0,hdb_loop 


DO.Low = Long word count 
DO.High = Byte count remainder 
Skip first time 


Get a long word 
Add hex to buffer 
Leave 2 spaces between groups 


Do next long word 


DO.W = remaining bytes (0-3) 
Skip first byte 
Get a byte 


Add to buffer 


Downie xt biyitie 


; Because we don’t always 


get 


16 bytes, we simply force Al to 


the 


7 desired Vocation in the output) butter: 

hd_ascii 
lea open_bracket ,al Wille hem c One pilitent ncmmaln: 
adda.w d5,al ; Adjust for extra linefeeds 
lea in_buffer ,a2 ; Back to the start of data 


move.w dl ,d0O 
move.b #’[’,(al)+ 


bra hda_next 


hda_loop 
move.b (a2)+,d2 
cmpi.b #space ,d2 
bcs.s hda_dot 
cmpi.b #max_char ,d2 
bcs.s hda_store 


hda_dot 
moveq #dot ,d2 


hda_store 
move.b d2,(al)+ 


hda_next 
dbf d0,hda_loop 


lea close_bracket ,al 
adda.w d5,al 

move.b #’]’ ,(al)+ 
move.b #linefeed ,(al ) 


’ 


> 


Data counter 
Opening delimiter added 


Skip first time 


Fetch byte of data 

We can print space or higher only 
This character is not ok 

Reached the icomtrol characters 7 
Noe thiissonie si fime 


Print a dot instead 


Save in output buffer 


And do the rest 

Wihere ston puitmthienss ||) 
Adjust for extra linefeeds 
Closing delimiter added 
And linefeed at the end 


31 


hd_print 
moveq #io_sstrg ,d0 
moveq #out_size ,d2 
add.w d5,d2 
lea out_buffer ,al 
move.1 dest_id(a7),a0 
trap #3 
tst.1 dO 
beq read_loop 


error_exit 
move.1 d0,d3 
bra.s suicide 


all_done 
moveq #0,d3 


suicide 
moveq #mt_frjob ,d0 
moveq #me,dl 
trap #1 


; Trap call we want 

; How many bytes? 

Adjust tom extras linieticiedis 
; Where our string is 

; Output channel 


DO meat 
; Did it work? 
5 WES, COMiMmne 


; Error code we want to return 
; And die 


Nome tion mcodie 


; This job is about to die 


> The hex ‘conversion rowtinies 


in QDOS are corrupt in some versions so 


; these will work. The take a long, word, byte or nibble in D4 and 
; write the hex byte(s) to a buffer pointed to by Al. 
; The various routines here call a lower level one, then drop into 
5 tne Collec COME ALAIN LO PROCESS TNs “OUNer Inalhe”’ Or Une Glatia 10 lore 
2 COmmerrtecl . 
hex_l 

swap d4 ; We do this in MS word order 

bsr.s hex_w ; Do original high word 

swap d4 ; Get low word back 
hex_w 

ror.w #8,d4 ; We do this in MS byte order 

bsr.s hex_b ; Do original high byte 

rol.w #8,d4 ; Get low byte back 
hex_b 

ror.b #4,d4 ; We do this in MS nibble order 

bsr.s hex_nibble ; Do original high nibble 

rol.b #4,d4 ; Get original low niggle back 
hex_nibble 


move.b d4,—(a7) 
andi.b #$0f ,d4 
addi.b #’0’ ,d4 
cmpi.b #’9’ ,d4 
bls.s hex_store 
addi.b #7,d4 


hex_store 
move.b d4,(al)+ 


3) We need™ tom save thie byte 

; Mask out low nibble 

; Assume digit 0—9 

ee Dateuite, 

5 Woes, Ghignt 

; Offset for an A-F character 


SeAdd stom the s buther sat Alle 
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ae move.b (a7)+,d4 +] Retnieve  orieinal byte 
rts 


Listing 4.2: Hexdump Utility 


4.0.5 Hexdump Code Explained 


As ever with my code, the first part is a load of bumff explaining briefly, sometimes, what the 
program should be doing. This utility is no different! Following on, we have a number of equates 
defined. The important ones here should be adequately commented - but we set up various offsets 
onto the A7 stack to extract the source file and destination channel ids and, not currently used here, 
where we should find the command string, if passed. 


Then there is the usual standard QDOS header for a job with the job name embedded and a couple 
of buffers. The input buffer is where we read the source file into, 16 bytes at a time. The output 
buffer is big enough to hold a printed output line of up to 80 characters. You may note that a 
program version has been defined, but is only for my own documentation, it is never display or 
used. Feel free to leave it out. 


The next couple of equates define the locations in the output buffer where the ’[’ and ’]’ surrounding 
the ASCII representation of the hex codes will be. 


Just before the main Hexdump code itself, we have the bad_parameter code which is, as you 
might expect, used to handle bad parameters - these are when we get less than or more than two 
channels on the stack at execution time. The utility simply exits with an error code back to the 
caller. 


Be aware that you will not see this error code if you EX the utility, only if you call it with EW will 
errors be reported back to SuperBasic. This is normal. 


Hexdump starts by checking the word on the stack to ensure that we only received two channel ids 
on the stack. If this is not the case, we exit via bad_parameter as explained above. Assuming this 
is not the case, we preload D3 with an infinite timeout. This is preserved through all trap calls, so 
only needs to be done once. 


We use D7 as the current offset counter, so we initialise it to zero, as we are still at the start of the 
source file. 


Read_loop is the start of the main loop. In here, we load the source file’s channel id into AO and 
read the next 16 bytes, maximum, into the input buffer. When we hit end of file, we need to ensure 
that the last few remaining bytes are converted to hex - if there was not exactly 16 bytes read when 
we hit EOF, they are still valid. We test D1 to be sure that we do have some data to process, if not, 
we are truly at EOF and we bale out of the utility passing a zero error code back to the caller. 


If there was some other error in the read, ie, not EOF, then we simply bale out and return the error 
code to the caller. 


Assuming all went well, we enter the code at read_ok where we set up A2 and A1 with the input 
and output buffer addresses respectively. As we want spaces in between each section of data in the 
output buffer, we fill all 80 bytes with spaces, prior to each conversion, at ob_clear. DS is cleared 
here as well, on each pass, as it counts the number of extra linefeeds that have been injected into 
the output buffer - zero or one - and is used to adjust various pointers and counts as necessary. 


The code at hd_address copies the current offset from D7 into D4 and if this is the start of the file 
- the offset is zero - skips over the next bit. Assuming that this is not the start of the file, we wish 
to insert an extra linefeed after every 256 bytes of the input file. This is easy to accomplish as we 


4.0.6 
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simply need to check the lowest byte of the offset. If it is zero, then we add a linefeed to the buffer 
and set DS to | to show the extra byte. This happens at offsets $0100, $0200, $0300 and so on. 


Prior to updating D7 with the count of the bytes just read. For most of the file, this will be 16 but 
there may be less at EOF. As the offset in D7 is long sized - we could be dumping large files - we 
have to extent D1 from a word to a long prior to the addition. D4 is converted from an offset to 
8 hex characters in a call to hex_1 which adds the converted characters to the output buffer and 
updates A1. 


After the address has been added, we wish to have 4 spaces after it, so Al is incremented by 4 to 
account for this. We are now ready to convert the data. 


Hd_data is where this happens. The bytes read is copied to DO as a long word and then divided by 
4 to get the number of long words read in. In most cases this will be 4, at least until we get to EOF. 
After the division, the low word of DO holds the number of long words to convert and the high 
word holds the remaining bytes to convert afterwards. Each long word is converted by copying it to 
D4.L and calling out to the hex_1 code again to convert and add it to the buffer as 8 hex characters. 
Two spaces are then ‘added’ by incrementing A1 accordingly. 


After all the long words are converted, we process the remaining bytes by swapping DO around so 
that the remaining bytes are in the low word, and we loop around those converting them one byte at 
atime at hdb_loop. 


After all the bytes are processed and added to the buffer, we need to add in the ASCII characters. 
Only printable ones will be considered - those between ‘space’ and the down arrow character, 
inclusive. Anything less than a space or any of the control characters from $CO upwards are 
represented by a dot. 


The first part of the code at hd_ascii adds an opening bracket to the buffer, then the individual 
ASCII characters are added, all 16 (usually) of them, then a closing bracket is added to the buffer 
followed by a linefeed. If we injected an extra linefeed previously, then D5 is added to the offsets 
for the opening and closing brackets to ensure that they are inserted into the buffer at the correct 
location. 


We then drop into hd_print where we send the completed buffer, to the destination file or channel 
before looping around and back to read_loop to do it all again. Once again, the counter in D2 
which determines the size of the string to print has to be adjusted to account for any extra linefeeds, 
so D5 is added to D2 before the TRAP #3. 


In the unlikely event of an error during the conversion to hex, the code at error_exit will be 
executed to copy the error code from DO into D3 prior to returning to the caller. If there were no 
errors, then all_done will cause a zero to be returned. The job then kills itself which will cleanly 
close the input and output files, flushing any buffers as appropriate. 


Hex Conversion 


As noted in the comments, certain versions of QDOS, prior to 1.03 I believe, have hex conversion 
routines in the ROM, but they are somewhat broken. To this end, I have supplied my own. To use 
them, D4 should contain the value to be converted and Al should point to a location in a buffer, 
somewhere, for the results. After conversion, Al is updated to the next free location in the buffer. 


The following is a sample of the output from the utility when used to hexdump an earlier incarnation! 
of itself. 


1A much earlier version! 
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00000000 
00000010 
00000020 
00000030 
00000040 
00000050 
00000060 
00000070 
00000080 
00000090 
000000A0 
000000B0 
000000C0 
000000D0 
000000E0 
000000F0 


00000100 
00000110 
00000120 
00000130 
00000140 
00000150 
00000160 


60000078 
756D7000 
00000000 
66EDE055 
00000000 
00000000 
00000000 
00000000 
76FF4287 

4E434A80 
4A416700 
13BC0020 
617CD3FC 
281A616A 
6004181A 
FF243001 


00206506 
FFEC43FA 
744943FA 
FF542600 
61024844 
1F040204 
06040007 


00000000 
61736D00 
00000000 
00010002 
00000000 
00000000 
00000000 
70F16000 
206F0002 
67100C80 
009245FA 
000051C8 
00000004 
D3FC0000 
616451C8 
12FCOO5B 


0C0200C0 
FF5712FC 
FFO0206F 
60027600 
E05C6102 
000F0604 
12C4181F 


4AFBO0007 
00000000 
00000000 
00000000 
00000000 
00000000 
00000000 
00C00C57 
43 FAFF8A 
FFFFFFF6 
FF6C43FA 
FFF82807 
200180FC 
000251C8 
FFFA43FA 
60000014 


6502742E 
005D12BC 
00064E43 
700572 FF 
E15CE81C 
00300C04 
4E75 


48657864 
00000000 
00000000 
00000000 
00000000 
00000000 
00000000 
000266F4 
74107003 
66000094 
FF78704F 
48CIDE81 
0004600A 
FFF44840 
FF6E45FA 
141A0C02 


12C251C8 
000A7007 
4A806700 
4E414844 
6102E91C 
00396304 


Listing 4.3: Example Hexdump Output 


[Re eexe J Hexd ] 
[ump.asm......... ] 
Rear eee reece ] 
fit S Ue eS ] 


[ie Dee oe Wee fee] 
Dvelbo. Ooo(Coes toda 
[NG ee ieee 
[JAg...E..1C..xpO] 
[es EOe GH s |] 
DEM eee) ee oe ee || 
[iC saliee ee Q...H@] 
[ie ade ee nr | 
[ieee Oy eeercr |e peeeneiee ] 
Claes Goth ooeQall 
sCLW. leoco Dal 
Cacn Oc, NCU] 

] 


] 
Renee OncoD Ce) 
[pee eeere Nu ] 


Imagine that your next great programming wonder is not based on the Pointer Environment, but 
does display a menu to the user with a number of options!. Each option can be selected by a single 
key press, and your application code has to choose a piece of code, a subroutine, to handle the 
user’s choice. 


You could do something like the following, where we assume that only the 10 digits are allowed 
and that DO.B holds the keypress character from the menu. 


main_loop 
bsr display_menu ; CLS and display the menu 
bsr get_menu_option ; Wait for a menu choice 


got_menu_option 


cmpi.b #’0’,d0 ; Zero or above? 
bes bad_option ; Oops 
cmpi.b #’9’ ,d0 ; Nine or below? 
bcc bad_option ; Oops 


got_good_option 
cmpi.b #’0’,d0 


beq option_0O ; Process option ’0’ 
cmpi.b #’1’,d0 
beq option_l OGE Ss Seno pitaommun all: 


cmpi.b #’8’,d0 


beq option_8 7 Process option 33) 
cmpi.b #’9’ ,d0 ; Not strictly required, but safe 
beq option_9 7 Process option: ~9 


'Tt wouldn’t be much of a menu otherwise, would it? :-) 
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option_return 
7 do; some post routine cleanmup here 
bra main_loop ; Ready for the next option 


option_0O 
7 PROCESS sO plLlione Zenon here 


bra option_return ; Back to the main loop 


option_l 
7 Process option one hener 


bra option_return ; Back to the main loop 


Listing 5.1: Processing User Options - First Attempt 


Ignoring the fact that there are numerous helper routines called, but not shown in the above example, 
then we can see that the above is quite simple to read and is fine for a small number of options. 
However, note that none of the option handling subroutines can use an RTS instruction to exit, as 
the call to the subroutine was by way of a BEQ instruction. They must therefore execute a bra 
option_return to get back into the clean up code and back to the main loop. 


We could improve matters slightly and use the PEA here to set up a pseudo subroutine call, by 
pushing the common_return address onto the stack prior to calling any of the subroutines, as 
follows. 


main_loop 
bsr display_menu ; CLS and display the menu 
bsr get_menu_option » Wait ton a menu) c¢ hice 


got_menu_option 


cmpi.b #’0’ ,d0 ~ Zero) OL above? 
bcs bad_option ; Oops 
cmpi.b #’9’ ,d0 ; Nine or below? 
bee bad_option Oops 


got_good_option 
pea option_return 7 Stack a return Sadidmess 


cmpi.b #’0’,d0 


beq option_0O 2 JPFOCERS OpinoOm 0)” 
cmpi.b #’9’ ,d0 ; Not strictly required, but safe 
beq option_9 2 JPFOCESS Opinom ~Y)” 


option_return 
; do some post routine clean up here 


bra main_loop ; Ready for the next option 


OADM KWN KR 
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option_0O 
~ Process soptions zero. here. 


rts 7 Back to option retmnn 


option_l 
HT PErOcess oO ptlonm one: hiener 


rts ; Back to option_return 


Listing 5.2: Processing User Options - Improved First Attempt 


This version is a lot better, while we are still calling the subroutines with a BEQ instruction, we have 
fiddled the stack by pushing a common return address onto it when we know we have a valid menu 
option. When each individual subroutine executes the RTS at the end, it will pop the address of 
option_return and continue executing from there. 


We could, if we wished to use the actual BSR instruction, perhaps to avoid confusion, code something 
like the following. 


main_loop 
bsr display_menu ; CLS and display the menu 
bsr get_menu_option ; Wait for a menu choice 


got_menu_option 


cmpi.b #’0’ ,d0 AeCLOmOl above, 
bcs bad_option ; Oops 
cmpi.b #’9’ ,d0 ; Nine or below? 
bec bad_option ; Oops 


got_good_option 
cmpi.b #’0’,d0 


bne.s ggo_try_l ; Not zero 

bsr option_0O 2 JPFOCESS OpinGm 0)” 

bra option_return ; Do cleanup 
ggo_try_l 

cmpi.b #’1’,d0 

bne.s ggo_try_2 e INo@t 7 il 

bsr option_1l 7 Process: options a 

bra option_return ; Do cleanup 
ggo_try_8 

cmpi.b #’8’ ,d0 

bne.s ggo_try_9 & INI@E OR 

bsr option_8 2 JPFOCESS OpPi@ml 6)” 

bra option_return ; Do cleanup 


ggo_try_9 


nABWN Ee 


cot O 
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cmpi.b #’°9’ ,d0 7 Not strictly nequined but sate 
bne.s option_return 5 IN 9) 

bsr option_9 2 JPFOCESS Opinom ~Y)” 

bra option_return ; Do cleanup 


option_return 
; do some post routine clean up here 
bra main_loop ; Ready for the next option 


option_0O 
5 PROCESS Opinom ZZeEKO® Ineire 


rts 
option_l 


HETOCeSS MO PULOM One. wmlener 


Ets 


Listing 5.3: Processing User Options - Another Improved First Attempt 


So, in this version, we are using the BSR instruction that we wanted to, but now we’ve had to invert 
all the flag checks after the cmpi.b #whatever ,dO and add in numerous new labels and branches, 
plus, after a successful return from the subroutine, we need an explicit branch to the clean up code 
at the bottom of the loop. It’s all getting rather messy now. 


You can imagine that as we add more and more menu options, that adding in new subroutines etc 
could get a bit frantic, especially trying to remember to do all the branches etc. In addition, there’s 
much more typing, and, if you type like I do, too much room for errors! 


Jump tables are easily set up, and can make life so much easier, with a lot less typing, although, it 
could be said that they are slightly less easily understood’. 


? 


JumpTable 
dc.w option_O0—JumpTable 
dc.w option_!—JumpTable 
dc.w option_2—JumpTable 
dc.w option_3—JumpTable 
dc.w option_4—JumpTable 
dc.w option_5—JumpTable 
dc.w option_6—JumpTable 
dc.w option_7—JumpTable 
dc.w option_8—JumpTable 
dc.w option_9—JumpTable 


main_loop 


*T’ve been in the IT business since around 1982, I still cannot touch type, I have to look at the keyboard to see where 
the next key I want is hiding! 
3At least until you begin to understand exactly how useful they really are! 
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bsr display_menu ; CLS and display the menu 
bsr get_menu_option ; Wait for a menu choice 


got_menu_option 


cmpi.b #’0’,d0 ; Zero or above? 
bcs bad_option ; Oops 
cmpi.b #’9’ ,d0 ; Nine or below? 
bec bad_option ; Oops 
got_good_option 
subq.b #’0’ ,d0 = DORB=.0) stom OSasiea numiben 
ext.w d0 ; Now extend to a word 
lsl.w #1,d0 5 (COMWEt TO a Table Oilmisen 
lea JumpTable , a2 ; Where the jump table lives 
jsr (a2,d0.w) ; Jump to the correct subroutine 


option_return 
; do some post routine clean up here 
bra main_loop ; Ready for the next option 


option_0O 
TORLOCeE Ss OplloneZenOmnehen 


rts 
option_l 
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Listing 5.4: Processing User Options - Jump Tables 


Each entry in the table surprisingly names JumpTable is a word sized signed offset to the desired 
routine, from the start of the table itself. This allows for subroutines that are located prior to, or 
after, the jump table being defined. Negative offsets are to subroutines defined before the table, and 
positive offsets are to subroutines defined after the jump table. Simple? 


You can see how much less code there is at the label got_good_option. At that point all we have 
to do is convert DO.B from a byte, containing one of the characters ‘0’ through ‘9’, into a word 
containing the numeric value zero to nine, as opposed to the character ‘0’ to ‘9’, then double it as 
each entry in the table takes two bytes. The offset to the option_0 subroutine is at JumpTable + 0, 
while that for the option_1 subroutine is at JumpTable + 2 and so on. 


Obviously, the code at main_loop is executed without passing through the preceding jump table, 
or who knows what might happen! Jump tables are data, not code. 


The jsr (a2,d0.w) takes care of calling the correct routine, as A2 is pre-loaded with the address 
of JumpTable. On return, we drop into the clean up code and pass back to the main loop start 
again. Remember, DO.W will be sign extended to a long word prior to adding it to A2.L. 


5.0.7 
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Adding new options is a simple matter of inserting or appending a new entry to the jump table in 
the correct place, and making sure that DO.W is set equal to the offset in the jump table, so that 
when we execute the jsr (a2,d0.w) instruction, we get the correct subroutine address. 


What About Missing Options 


So far so good, our table holds one subroutine offset for each menu option from ‘0’ to ‘9’, which 
gets translated to a value between 0 and 9, and subsequently, into an offset into the table of offset 
words*. What do we do if, for example, option 5 is not actually allowed? We have a couple of 
choices: 


e Filter out the illegal option(s) when checking for a valid choice. 
e Use a ‘do nothing’ entry for the invalid choice(s) in the table. 
e Use a zero offset in the table,test for it in the and don’t jump if that is found. 


The first option is obviously the best as it gives you the opportunity to advise the user of their error 
when they try to make an invalid choice. The last option would require a slight change to the code 
at got_good_option, as follows: 


got_good_option 
subq.b #’0’ ,dO 7 DOEBe— OM tom Olass aa number 
ext.w dO ; Now extend to a word 
lsl.w #1,d0 aeConvernt toma tabllew ont sient 
lea JumpTable , a2 ; Where the jump table lives 
tst.w (a2 ,d0.w) 2 Weallicl @iritsen? 
beq.s no_jump ; No, do nothing 
jsr (a2 ,d0.w) ; Jump to the correct subroutine 


Listing 5.5: Processing User Options - Jump Tables 


The code at label no_ jump would do whatever is required prior to the next pass through the main 
loop. 


4Ugh! Too many offsets in that sentence! 


020 Instructions 


As you may be aware, in all of the articles I published in QL Today over the years, and in the 
preceding issues of this randomly occurring eMagazine, I’ve been a loyal user of George’s Gwasl 
assembler. This worked well on old black box QLs but who is using one of those these days? 
Anyone? 


It is time to move on from the toys and playthings of childhood and become a real [wo]man. From 
the next issue, issue 4, we are going to switch to George’s other assembler, Gwass and get down 
and dirty using the 68020 instructions. If you are using QPC, then you are already able to use them 
as George had a hand in getting QPC running on an emulated 68020 rather than a simple 68008 as 
the old Black Boxes used to run. 


How many of my readers will this upset I wonder? Table 6.1 gives details of which computer or 
emulator can handle the new instructions. 


Computer Processor Comments 


QL 68008 Cannot use the new instructions. 
QPC 68020 Able to use the new instructions. 


Others 68008 Cannot use the new instructions 
Table 6.1: Emulators and the 68020 


This is a problem perhaps? Does anyone not use QPC for their main “QL on a PC”? Would some 
or all of my readers be missing out if I went down this route? 


You better let me know, soon(ish) at the usual email address assembly@qdosmsq.dunbar-it.co. 
uk. 


